home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / Statement.java < prev    next >
Text File  |  1998-09-22  |  11KB  |  265 lines
  1. /*
  2.  * @(#)Statement.java    1.7 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.sql;
  16.  
  17. /**
  18.  * <P>A Statement object is used for executing a static SQL statement
  19.  * and obtaining the results produced by it. 
  20.  *
  21.  * <P>Only one ResultSet per Statement can be open at any point in
  22.  * time. Therefore, if the reading of one ResultSet is interleaved
  23.  * with the reading of another, each must have been generated by
  24.  * different Statements. All statement execute methods implicitly
  25.  * close a statment's current ResultSet if an open one exists.
  26.  *
  27.  * @see Connection#createStatement
  28.  * @see ResultSet 
  29.  */
  30. public interface Statement {
  31.  
  32.     /**
  33.      * Execute a SQL statement that returns a single ResultSet.
  34.      *
  35.      * @param sql typically this is a static SQL SELECT statement
  36.      * @return a ResultSet that contains the data produced by the
  37.      * query; never null 
  38.      * @exception SQLException if a database-access error occurs.
  39.      */
  40.     ResultSet executeQuery(String sql) throws SQLException;
  41.  
  42.     /**
  43.      * Execute a SQL INSERT, UPDATE or DELETE statement. In addition,
  44.      * SQL statements that return nothing such as SQL DDL statements
  45.      * can be executed.
  46.      *
  47.      * @param sql a SQL INSERT, UPDATE or DELETE statement or a SQL
  48.      * statement that returns nothing
  49.      * @return either the row count for INSERT, UPDATE or DELETE or 0
  50.      * for SQL statements that return nothing
  51.      * @exception SQLException if a database-access error occurs.
  52.      */
  53.     int executeUpdate(String sql) throws SQLException;
  54.  
  55.     /**
  56.      * In many cases, it is desirable to immediately release a
  57.      * Statements's database and JDBC resources instead of waiting for
  58.      * this to happen when it is automatically closed; the close
  59.      * method provides this immediate release.
  60.      *
  61.      * <P><B>Note:</B> A Statement is automatically closed when it is
  62.      * garbage collected. When a Statement is closed, its current
  63.      * ResultSet, if one exists, is also closed.  
  64.      *
  65.      * @exception SQLException if a database-access error occurs.
  66.      */
  67.     void close() throws SQLException;
  68.  
  69.     //----------------------------------------------------------------------
  70.  
  71.     /**
  72.      * The maxFieldSize limit (in bytes) is the maximum amount of data
  73.      * returned for any column value; it only applies to BINARY,
  74.      * VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR
  75.      * columns.  If the limit is exceeded, the excess data is silently
  76.      * discarded.
  77.      *
  78.      * @return the current max column size limit; zero means unlimited 
  79.      * @exception SQLException if a database-access error occurs.
  80.      */
  81.     int getMaxFieldSize() throws SQLException;
  82.     
  83.     /**
  84.      * The maxFieldSize limit (in bytes) is set to limit the size of
  85.      * data that can be returned for any column value; it only applies
  86.      * to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and
  87.      * LONGVARCHAR fields.  If the limit is exceeded, the excess data
  88.      * is silently discarded. For maximum portability use values
  89.      * greater than 256.
  90.      *
  91.      * @param max the new max column size limit; zero means unlimited 
  92.      * @exception SQLException if a database-access error occurs.
  93.      */
  94.     void setMaxFieldSize(int max) throws SQLException;
  95.  
  96.     /**
  97.      * The maxRows limit is the maximum number of rows that a
  98.      * ResultSet can contain.  If the limit is exceeded, the excess
  99.      * rows are silently dropped.
  100.      *
  101.      * @return the current max row limit; zero means unlimited
  102.      * @exception SQLException if a database-access error occurs.
  103.      */
  104.     int getMaxRows() throws SQLException;
  105.  
  106.     /**
  107.      * The maxRows limit is set to limit the number of rows that any
  108.      * ResultSet can contain.  If the limit is exceeded, the excess
  109.      * rows are silently dropped.
  110.      *
  111.      * @param max the new max rows limit; zero means unlimited 
  112.      * @exception SQLException if a database-access error occurs.
  113.      */
  114.     void setMaxRows(int max) throws SQLException;
  115.  
  116.     /**
  117.      * If escape scanning is on (the default), the driver will do
  118.      * escape substitution before sending the SQL to the database.
  119.      *
  120.      * Note: Since prepared statements have usually been parsed prior
  121.      * to making this call, disabling escape processing for prepared
  122.      * statements will like have no affect.
  123.      *
  124.      * @param enable true to enable; false to disable
  125.      * @exception SQLException if a database-access error occurs.
  126.      */
  127.     void setEscapeProcessing(boolean enable) throws SQLException;
  128.  
  129.     /**
  130.      * The queryTimeout limit is the number of seconds the driver will
  131.      * wait for a Statement to execute. If the limit is exceeded, a
  132.      * SQLException is thrown.
  133.      *
  134.      * @return the current query timeout limit in seconds; zero means unlimited 
  135.      * @exception SQLException if a database-access error occurs.
  136.      */
  137.     int getQueryTimeout() throws SQLException;
  138.  
  139.     /**
  140.      * The queryTimeout limit is the number of seconds the driver will
  141.      * wait for a Statement to execute. If the limit is exceeded, a
  142.      * SQLException is thrown.
  143.      *
  144.      * @param seconds the new query timeout limit in seconds; zero means unlimited 
  145.      * @exception SQLException if a database-access error occurs.
  146.      */
  147.     void setQueryTimeout(int seconds) throws SQLException;
  148.  
  149.     /**
  150.      * Cancel can be used by one thread to cancel a statement that
  151.      * is being executed by another thread.
  152.      *
  153.      * @exception SQLException if a database-access error occurs.
  154.      */
  155.     void cancel() throws SQLException;
  156.  
  157.     /**
  158.      * The first warning reported by calls on this Statement is
  159.      * returned.  A Statment's execute methods clear its SQLWarning
  160.      * chain. Subsequent Statement warnings will be chained to this
  161.      * SQLWarning.
  162.      *
  163.      * <p>The warning chain is automatically cleared each time
  164.      * a statement is (re)executed.
  165.      *
  166.      * <P><B>Note:</B> If you are processing a ResultSet then any
  167.      * warnings associated with ResultSet reads will be chained on the
  168.      * ResultSet object.
  169.      *
  170.      * @return the first SQLWarning or null 
  171.      * @exception SQLException if a database-access error occurs.
  172.      */
  173.     SQLWarning getWarnings() throws SQLException;
  174.  
  175.     /**
  176.      * After this call, getWarnings returns null until a new warning is
  177.      * reported for this Statement.  
  178.      *
  179.      * @exception SQLException if a database-access error occurs.
  180.      */
  181.     void clearWarnings() throws SQLException;
  182.  
  183.     /**
  184.      * setCursorname defines the SQL cursor name that will be used by
  185.      * subsequent Statement execute methods. This name can then be
  186.      * used in SQL positioned update/delete statements to identify the
  187.      * current row in the ResultSet generated by this statement.  If
  188.      * the database doesn't support positioned update/delete, this
  189.      * method is a noop.
  190.      *
  191.      * <P><B>Note:</B> By definition, positioned update/delete
  192.      * execution must be done by a different Statement than the one
  193.      * which generated the ResultSet being used for positioning. Also,
  194.      * cursor names must be unique within a Connection.
  195.      *
  196.      * @param name the new cursor name.  
  197.      * @exception SQLException if a database-access error occurs.
  198.      */
  199.     void setCursorName(String name) throws SQLException;
  200.     
  201.     //----------------------- Multiple Results --------------------------
  202.  
  203.     /**
  204.      * Execute a SQL statement that may return multiple results.
  205.      * Under some (uncommon) situations a single SQL statement may return
  206.      * multiple result sets and/or update counts.  Normally you can ignore
  207.      * this, unless you're executing a stored procedure that you know may
  208.      * return multiple results, or unless you're dynamically executing an
  209.      * unknown SQL string.  The "execute", "getMoreResults", "getResultSet"
  210.      * and "getUpdateCount" methods let you navigate through multiple results.
  211.      *
  212.      * The "execute" method executes a SQL statement and indicates the
  213.      * form of the first result.  You can then use getResultSet or
  214.      * getUpdateCount to retrieve the result, and getMoreResults to
  215.      * move to any subsequent result(s).
  216.      *
  217.      * @param sql any SQL statement
  218.      * @return true if the next result is a ResultSet; false if it is
  219.      * an update count or there are no more results
  220.      * @exception SQLException if a database-access error occurs.
  221.      * @see #getResultSet
  222.      * @see #getUpdateCount
  223.      * @see #getMoreResults 
  224.      */
  225.     boolean execute(String sql) throws SQLException;
  226.     
  227.     /**
  228.      *  getResultSet returns the current result as a ResultSet.  It
  229.      *  should only be called once per result.
  230.      *
  231.      * @return the current result as a ResultSet; null if the result
  232.      * is an update count or there are no more results
  233.      * @exception SQLException if a database-access error occurs.
  234.      * @see #execute 
  235.      */
  236.     ResultSet getResultSet() throws SQLException; 
  237.  
  238.     /**
  239.      *  getUpdateCount returns the current result as an update count;
  240.      *  if the result is a ResultSet or there are no more results, -1
  241.      *  is returned.  It should only be called once per result.
  242.      * 
  243.      * @return the current result as an update count; -1 if it is a
  244.      * ResultSet or there are no more results
  245.      * @exception SQLException if a database-access error occurs.
  246.      * @see #execute 
  247.      */
  248.     int getUpdateCount() throws SQLException; 
  249.  
  250.     /**
  251.      * getMoreResults moves to a Statement's next result.  It returns true if 
  252.      * this result is a ResultSet.  getMoreResults also implicitly
  253.      * closes any current ResultSet obtained with getResultSet.
  254.      *
  255.      * There are no more results when (!getMoreResults() &&
  256.      * (getUpdateCount() == -1)
  257.      *
  258.      * @return true if the next result is a ResultSet; false if it is
  259.      * an update count or there are no more results
  260.      * @exception SQLException if a database-access error occurs.
  261.      * @see #execute 
  262.      */
  263.     boolean getMoreResults() throws SQLException; 
  264. }    
  265.